//Copyright (c) Microsoft Corporation.  All rights reserved.

using System;
using System.Collections.Generic;
using System.Text;

namespace Eas.WebCrawler.Interfaces {
    /// <summary>Abstracts away temporary storage of the contents of a stream so that it can be accessed later.</summary>
    /// <remarks>After the web crawler encounters a request, it starts to download the contents of the page for that request.  
    /// It needs to store those contents somewhere, and an instance of TemporaryStorage provides the 'where'.
    /// Once the crawler has retrieved the stream representing the contents of a web page, it determines if the contents are
    /// text (like html) or binary (like pictures).  It then asks the TemporaryStorage for either a binary or text writer, and 
    /// writes the contents of the file.  The crawler then notifies any interested parties that the request is processed, and it 
    /// passes to those interested parties the TemporaryStorage.  Those parties can get a reader from the storage in order to access
    /// those contents.
    /// </remarks>
    public interface TemporaryStorage : IDisposable {
        /// <summary>Provides a <see cref="System.IO.TextReader"/> for reading contents stored in this store.</summary>
        /// <returns>A <see cref="System.IO.TextReader"/> for reading contents stored in this store.</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate")]
        System.IO.TextReader GetTextReader();

        /// <summary>Provides a <see cref="System.IO.TextWriter"/> for writing contents into this store.</summary>
        /// <returns>A <see cref="System.IO.TextWriter"/> for writing contents into this store.</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate")]
        System.IO.TextWriter GetTextWriter();

        /// <summary>Provides a <see cref="System.IO.BinaryReader"/> for reading contents stored in this store.</summary>
        /// <returns>A <see cref="System.IO.BinaryReader"/> for reading contents stored in this store.</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate")]
        System.IO.BinaryReader GetBinaryReader();

        /// <summary>Provides a <see cref="System.IO.BinaryWriter"/> for writing contents into this store.</summary>
        /// <returns>A <see cref="System.IO.BinaryWriter"/> for writing contents into this store.</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate")]
        System.IO.BinaryWriter GetBinaryWriter();
    }

    /// <summary>Creates instances of <see cref="TemporaryStorage"/>.</summary>
    /// <remarks>The web crawler uses an instance of this class to store the contents of downloaded pages (requests).</remarks>
    public interface TemporaryStorageFactory : Eas.WebCrawler.Interfaces.WebCrawlerComponent{
        /// <summary>Creates a new instance of a <see cref="TemporaryStorage"/>.</summary>
        /// <param name="processingState">The <see cref="ProcessingState"/> for the current request.</param>
        /// <returns>A new instance of a <see cref="TemporaryStorage"/>.</returns>
        TemporaryStorage Create(ProcessingState processingState);
    }
}
